package cz.cuni.mff.ufal.volk.services;

import cz.cuni.mff.ufal.volk.Expression;
import cz.cuni.mff.ufal.volk.UnsupportedLanguageException;
import cz.cuni.mff.ufal.volk.il.Node;

/**
 * A common natural language understander. It is used for converting natural language
 * expressions into the tectogrammatical representation.
 * 
 * @author Bartłomiej Etenkowski
 * @param  <T> the type of processed objects
 */
public interface Understander<T extends Expression> {
  
  /**
   * Tries to <i>understand</i> the natural language item given as parameter. It tries
   * to convert the expression into the Intermediate Language. The context can be used during 
   * the understanding process, however, it should not be modified in the third layer.
   * 
   * <p>It is possible that the understander will not be able to understand the message
   * completely (it is also possible that it will not understand it at all). In this case,
   * the result {@link Node} should contain a subnode marked with {@code understood=false}
   * attribute.</p>
   * 
   * @param  item the message which has to be understood
   * @return tectogrammatical representation of the natural language expression 
   *         in the intermediate language      
   * 
   * @throws NullPointerException if the item parameter is {@code null}
   * @throws UnsupportedLanguageException if the language of the message is not supported
   *         by the understander
   */
  Node understand(T item) throws UnsupportedLanguageException;
  
}
